// File: jmcomic-core/src/main/java/dev/jukomu/common/base/concurrent/StopFlagManager.java
package dev.jukomu.common.base.concurrent;

/**
 * 对应Python的ThreadFlagManager，管理StopFlag的便利类。
 */
public class StopFlagManager {

    protected final StopFlag stopFlag;

    /**
     * 构造函数。
     *
     * @param stopFlag StopFlag实例。
     */
    public StopFlagManager(StopFlag stopFlag) {
        this.stopFlag = stopFlag;
    }

    /**
     * 获取关联的StopFlag实例。
     *
     * @return StopFlag实例。
     */
    public StopFlag getStopFlag() {
        return stopFlag;
    }

    /**
     * 当收到停止信号时通知回调。
     * 默认空实现，子类可覆盖。
     */
    protected void noticeStopCallback() {
        // Default empty implementation, can be overridden by subclasses
    }

    /**
     * 休眠一段时间，并在休眠期间定期检查停止标志。
     * 如果应该停止，则抛出停止异常。
     *
     * @param durationSeconds 休眠总时长（秒）。
     * @throws InterruptedException 如果应该停止或休眠被中断。
     */
    public void sleepOrRaise(double durationSeconds) throws InterruptedException {
        stopFlag.sleepOrRaise(durationSeconds);
    }

    /**
     * 如果应该停止，则抛出停止异常。
     *
     * @throws InterruptedException 如果应该停止。
     */
    public void ifStopRaise() throws InterruptedException {
        if (isStop()) { // 先调用isStop()触发回调
            stopFlag.raiseStopException();
        }
    }

    /**
     * 休眠一段时间，并在休眠期间定期检查停止标志。
     *
     * @param durationSeconds 休眠总时长（秒）。
     * @param partSeconds     每次检查停止标志的间隔（秒）。
     * @return 如果在休眠期间收到停止信号返回 true，否则返回 false。
     * @throws InterruptedException 如果休眠被中断。
     */
    public boolean sleepOrReturn(double durationSeconds, double partSeconds) throws InterruptedException {
        boolean shouldStop = stopFlag.sleepOrReturn(durationSeconds, partSeconds);
        if (shouldStop) {
            noticeStopCallback();
        }
        return shouldStop;
    }

    /**
     * 休眠一段时间，并在休眠期间定期检查停止标志。
     * 使用默认的检查间隔0.5秒。
     *
     * @param durationSeconds 休眠总时长（秒）。
     * @return 如果在休眠期间收到停止信号返回 true，否则返回 false。
     * @throws InterruptedException 如果休眠被中断。
     */
    public boolean sleepOrReturn(double durationSeconds) throws InterruptedException {
        return sleepOrReturn(durationSeconds, 0.5);
    }

    /**
     * 检查是否应该停止。
     * 如果是停止状态，会触发noticeStopCallback。
     *
     * @return 如果应该停止返回 true。
     */
    public boolean isStop() {
        boolean shouldStop = stopFlag.shouldStop();
        if (shouldStop) {
            noticeStopCallback();
        }
        return shouldStop;
    }
}